Sphinxで階層構造のサイドメニューを利用する(HTMLサイト)

Sphinxで階層構造のサイドメニューを利用する(HTMLサイト)

Sphinxで階層構造のサイドメニューを試してみました。
Clock Icon2023.09.25

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

Sphinxは、文章作成ツールのひとつです。 ソースコードの関数コメントからAPIドキュメントを作成したり、reStructuredText形式のテキストドキュメントから、HTMLファイルを作成できます。 拡張機能を利用すれば、Markdown形式のテキストドキュメントも扱えます。

今回は、HTMLサイトで階層構造のサイドメニューを試してみます。

おすすめの方

  • Sphinxについて知りたい方
  • Sphinxで階層構造のサイドメニューを利用したい方(HTMLサイト)

Sphinxを使う準備をする

Sphinxを導入する

公式の手順に従って、導入します。

適当なプロジェクトを作成する

公式の手順に従って、適当なプロジェクトを作成します。

sphinx-quickstart docs

ビルドする

HTMLサイトをビルドします。

cd docs
make html

ビルド後は、下記のファイルを開いて、確認します。

open build/html/index.html

Sphinxのデフォルト状態

階層構造のサイドメニューを利用する

サイドメニューの構成を決める

適当にサイドメニューの構成を決めます。今回は次のようにしてみます。

  • 北海道
    • 札幌市
    • 釧路市
    • 旭川市
  • 東京都
    • 千代田区
    • 品川区
    • 八王子市
  • 福岡県
    • 北九州市

rstファイルを作成する

docs/sourceに下記のファイルを作成します。

  • hokkaido.rst
  • sapporo.rst
  • kusiro.rst
  • asahikawa.rst
  • toukyo.rst
  • chiyoda.rst
  • shinagawa.rst
  • hachioji.rst
  • fukuoka.rst
  • kitakyushu.rst

rstファイルに toctree を設定する

それぞれ上位となるrstファイルに toctree を記載します。

index.rst


Welcome to test-blog's documentation!
=====================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   hokkaido
   toukyo
   fukuoka


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

hokkaido.rst

北海道
=====================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   sapporo
   kusiro
   asahikawa

sapporo.rst

札幌市
=====================================

kusiro.rst

釧路市
=====================================

asahikawa.rst

旭川市
=====================================

toukyo.rst

東京都
=====================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   chiyoda
   shinagawa
   hachioji

chiyoda.rst

千代田区
=====================================

shinagawa.rst

品川区
=====================================

hachioji.rst

八王子市
=====================================

fukuoka.rst

福岡県
=====================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   kitakyushu

kitakyushu.rst

北九州市
=====================================

ビルドして生成されたHTMLファイルを確認する

make html

階層構造のメニューができました。

Sphinxのサイドメニュー

それぞれのページに移動した際のサイドメニューは、下記となっています。

Sphinxのサイドメニュー

Sphinxのサイドメニュー

Sphinxのサイドメニュー

別のテーマでも試してみる

次のテーマを導入し、ビルドしてみました。

階層構造のメニューになりました。

Sphinxのサイドメニュー(別のテーマ)

さいごに

Sphinxで階層構造のサイドメニューにしてみました。 どなたかの参考になれば幸いです。

参考

Share this article

facebook logohatena logotwitter logo

© Classmethod, Inc. All rights reserved.